CMAIL

Section: Games and Demos (6)
Index Return to Main Contents

NAME

cmail - an email chess helper

SYNOPSIS

cmail [options]

DESCRIPTION

The cmail program will help you play chess by email with opponents of your choice using an X interface. To use it, you will need to be able to run xboard with which cmail is distributed, available by anonymous FTP from numerous sites around the world. It has been tested with xboard 3.1; it may require modification for other versions.

OPTIONS

You will usually run cmail without giving any options. See the next section for instructions.

-h: Displays cmail usage information.
-c: Shows the conditions of the GNU General Public License.
-w: Shows the warranty notice of the GNU General Public License.
-[x]v: Provides verbose output from cmail (not xboard) useful for debugging, or inhibits it. The -xv form also inhibits the cmail introduction message.
-[x]mail: Invokes or inhibits the sending of a mail message containing the move.
-[x]xboard: Invokes or inhibits the running of xboard on the game file.
-[x]reuse: Invokes or inhibits the reuse of an existing xboard to display the current game.
-remail: Resends the last mail message for that game. This inhibits running xboard.
-game name: The name of the game to be processed.
-opp name: An alias for the opponent.
-addr address: The opponent's email address.
-event event: The PGN Event tag (default "Email correspondence game").
-site site: The PGN Site tag (default "NET").
-round round: The PGN Round tag (default "-", not applicable).
-(white|black) name: The PGN White/Black name tag (default "?", unknown).
-(white|black)na net address: The PGN White/Black network address tag (default "?", unknown).
-mode mode: The PGN Mode tag (default "EM", Electronic Mail).
-dir directory: The directory in which cmail keeps its files. This defaults to the environment variable $CHESSDIR or failing that, $HOME/Chess or ~/Chess. It will be created if it does not exist.
-mailprog mail program: The program used by cmail to send email messages. This defaults to the environment variable $CMAIL_MAILPROG or failing that "/usr/ucb/Mail", "/usr/ucb/mail" or "Mail".
-gamesFile file: A file containing a list of games with email addresses. This defaults to the environment variable $CMAIL_GAMES or failing that .cmailgames.
-aliasesFile file: A file containing one or more aliases for a set of email addresses. This defaults to the environment variable $CMAIL_ALIASES or failing that .cmailaliases.
-logFile file: A file in which to dump verbose debugging messages that are invoked with the -v option.

OTHER OPTIONS

Any unrecognised flags will be passed to xboard. Those most relevant for use with cmail are:

-oldSaveStyle (True | False), or -[x]oldsave: If this option is True, xboard uses the old save style for saving games, rather than the new PGN format. Newer versions of cmail and xboard understand both formats automatically without using this flag, so it is only necessary on starting a new game where Black uses the old cmail (1.0).
-timeDelay (or -td) delay: This sets the speed at which the moves are displayed on start-up. It defaults to the environment variable $CMAIL_TIME_DELAY if set, and 0 otherwise.
-noChessProgram (True | False), or -[x]ncp: If this option is False, xboard starts a chess program which can be used with cmail to suggest moves. Default: True.
-searchTime (or -st) minutes[:seconds]: Tells GNU Chess to spend at most the given amount of time searching for each of its moves. Without this option, GNU Chess chooses its search time based on the number of moves and amount of time remaining until the next time control.
-searchDepth (or -sd) number: Tells GNU Chess to look ahead at most the given number of moves when searching for a move to make. Without this option, GNU Chess chooses its search depth based on the number of moves and amount of time remaining until the next time control.
-saveGameFile (or -sgf) file: If this option is set, xboard appends a record of the game played to the specified file on exit.
-autosave or -autoSaveGames: If this option is True, at the end of every game xboard prompts you for a filename and appends a record of the game to the file you specify.
-savePositionFile (or -spf) file: If this option is set, xboard appends the final position reached to the specified file on exit.
-boardSize (or -size) (Large | Medium | Small): Determines how large the board will be and what built-in piece bitmaps will be used. On a large board (the default), pieces are 80x80 pixels, on a medium board 64x64 pixels, and on a small board 40x40 pixels.

STARTING A GAME

Type cmail from a shell. After an opening message, you will be prompted for a game name, which is optional -- if you simply press return, the game name will take the form you-VS-opponent. You will next be prompted for the name of your opponent. If you haven't played this person before, you will also be prompted for his/her email address. cmail will then invoke xboard in the background. Make your first move and select Mail Move from the File menu. If all is well, cmail will mail a copy of the move to your opponent. If you select Exit without having selected Mail Move then no move will be made.

ANSWERING A MOVE

When you receive a message from an opponent containing a move in one of your games, simply pipe the message through cmail. In some mailers this is as simple as typing "| cmail" when viewing the message, while in others you may have to save the message to a file and do "cmail < file" at the command line. In either case cmail will display the game using xboard. If you didn't exit xboard when you made your first move then cmail will do its best to use the existing xboard instead of starting a new one. As before, simply make a move and select Mail Move from the File menu. cmail will try to use the xboard that was most recently used to display the current game. This means that many games can be in progress simultaneously, each with its own active xboard.

If you want to look at the history or explore a variation, go ahead, but you must return to the current position before xboard will allow you to mail a move. If you edit the game's history you must select Reload CMail Game from the File menu to get back to the original position, then make the move you want and select Mail Move. As before, if you decide you aren't ready to make a move just yet you can either select Exit without sending a move or just leave xboard running until you are ready.

TROUBLE SHOOTING

It's possible that a strange conjunction of conditions may occasionally mean that cmail has trouble reactivating an existing xboard. If this should happen trying it again might work. If not, remove the file that stores the xboard's PID (<game>.pid) or use the -xreuse option to force cmail to start a new xboard.

Older versions of cmail do not understand the PGN format which xboard now uses. If your opponent uses an older version of cmail you will need to use the -oldsave flag to initiate a game with him/her.

FILES

".cmailgames" contains a list of games with the email addresses of the opponents.

".cmailaliases" contains one or more aliases for a set of email addresses.

BUGS

No known bugs.

BUG REPORTS

I make no promises but if you send bug reports/suggestions to welsh@epcc.ed.ac.uk I'll do my best to fix/implement them.

AUTHOR

cmail is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

cmail is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with cmail; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Author:   Evan Welsh <welsh@epcc.ed.ac.uk>
          Edinburgh Parallel Computing Centre
          JCMB, Kings Buildings
          The University of Edinburgh
          Edinburgh EH9 3JZ
          Scotland

CONTRIBUTORS

Patrick Surry helped with design, testing and documentation.

Tim Mann helped integrate cmail with xboard.

This document was created by man2html, using the manual pages.
Time: 11:29:10 GMT, February 07, 2023